fix(lint): isolate pydoclint to end docstring-parser-fork collision#21
Merged
Merged
Conversation
pydoclint depends on `docstring-parser-fork`, which installs into the same `docstring_parser/` import namespace as the canonical `docstring-parser` that vgi_rpc imports at runtime (rpc/_types.py). With both in one venv, whichever uv installs last wins — a non-deterministic race. Unrelated dependency bumps (e.g. the cryptography 48->49 PR) reorder the install graph, so the canonical package can shadow the fork and drop symbols pydoclint needs (DocstringYields), crashing the lint gate with an ImportError. The failure was latent on main: the fork happened to win there. Remove pydoclint from the dev dependency group and run it isolated via `uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/` in CI and the local workflow. The project venv now resolves only the canonical docstring-parser; pydoclint (and its fork) live in an ephemeral uvx env. Lint is deterministic and no longer perturbed by unrelated bumps. - pyproject.toml: drop `pydoclint>=0.8` from dev group; document why; update the [tool.pydoclint] run instruction. - ci.yml: run pydoclint via uvx (--python 3.13 so it parses 3.13 syntax). - CLAUDE.md: update the step-3 command. - uv.lock: regenerated (pydoclint + docstring-parser-fork removed). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The Lint gate was flaky in a way that surfaced on the cryptography 48→49 Dependabot PR (#17): pydoclint crashed with
Root cause: pydoclint depends on
docstring-parser-fork, which installs into the samedocstring_parser/import namespace as the canonicaldocstring-parserthat vgi_rpc imports at runtime (rpc/_types.py). With both in one venv, whichever uv installs last wins — non-deterministic. Unrelated dependency bumps reorder the install graph; when the canonical package shadows the fork, the symbols pydoclint needs disappear and it crashes. The bug was latent onmain(the fork happened to win there), so it only appeared once #17 perturbed the order.docstring-parser-forkis pulled in only by pydoclint:Fix
Stop co-installing the fork with the canonical package: remove pydoclint from the dev group and run it isolated via uvx.
pydoclint>=0.8from the dev group; document why; update the[tool.pydoclint]run note.uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/(the--python 3.13is required so the isolated parser understands the package's 3.13 syntax).pydoclintanddocstring-parser-forkremoved. The project venv now resolves only canonicaldocstring-parser0.18.0.Verification
docstring_parser-0.18.0(no fork).from docstring_parser import DocstringStyle, parse→ ok.uvx --python 3.13 --from pydoclint==0.8.7 pydoclint vgi_rpc/→ 🎉 No violations.ruff format --check,ruff check,mypy,tyall clean.pytest(introspection/docstring/type subset) → 543 passed.Unblocks #17, which will pass Lint deterministically once rebased on this.
🤖 Generated with Claude Code